---
id: index
title: Typed Linting
slug: /troubleshooting/typed-linting
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## Editor ESLint reports become out-of-date after file changes

There is a known issue in at least VS Code with typed linting that files might have out-of-date lint errors after multiple updates to files on disk.
The root cause is that ESLint doesn't provide a way for editors to know about cross-file dependencies, such as type information.
This results in files receiving out-of-date type information when files they import from are changed.

You might see this as erroneous `no-unsafe-*` rule complaints on `any` or `error typed` values.
Other rules may be more subtly incorrect.

For now, the workaround is to run the _**Restart ESLint Server**_ command in VS Code (or an equivalent in other editors) when types get out of date.

See [ESLint does not re-compute cross-file information on file changes (microsoft/vscode-eslint#1774)](https://github.com/microsoft/vscode-eslint/issues/1774) for more information.

<HiddenHeading id="allowdefaultprojectforfiles-glob-too-wide" />

## I get errors telling me "Having many files run with the default project is known to cause performance issues and slow down linting."

These errors are caused by using the [`EXPERIMENTAL_useProjectService`](../../packages/Parser.mdx#experimental_useprojectservice) `allowDefaultProjectForFiles` with an excessively wide glob.
`allowDefaultProjectForFiles` causes a new TypeScript "program" to be built for each "out of project" file it includes, which incurs a performance overhead for each file.

To resolve this error, narrow the glob(s) used for `allowDefaultProjectForFiles` to include fewer files.
For example:

```diff title="eslint.config.js"
parserOptions: {
  EXPERIMENTAL_useProjectService: {
    allowDefaultProjectForFiles: [
-      "**/*.js",
+      "./*.js"
    ]
  }
}
```

You may also need to include more files in your `tsconfig.json`.
For example:

```diff title="tsconfig.json"
"include": [
  "src",
+ "*.js"
]
```

If you cannot do this, please [file an issue on typescript-eslint's typescript-estree package](https://github.com/typescript-eslint/typescript-eslint/issues/new?assignees=&labels=enhancement%2Ctriage&projects=&template=07-enhancement-other.yaml&title=Enhancement%3A+%3Ca+short+description+of+my+proposal%3E) telling us your use case and why you need more out-of-project files linted.
Be sure to include a minimal reproduction we can work with to understand your use case!

## I get errors telling me "ESLint was configured to run ... However, that TSConfig does not / none of those TSConfigs include this file"

These errors are caused by an ESLint config requesting type information be generated for a file that isn't included in the TypeScript configuration.

### Fixing the Error

<!-- prettier-ignore-start -->

- If you **do not** want to lint the file:
  - Use [one of the options ESLint offers](https://eslint.org/docs/latest/user-guide/configuring/ignoring-code) to ignore files, namely a `.eslintignore` file, or `ignorePatterns` config.
- If you **do** want to lint the file:
  - If you **do not** want to lint the file with [type-aware linting](../../getting-started/Typed_Linting.mdx):
    - Use [ESLint's `overrides` configuration](https://eslint.org/docs/latest/user-guide/configuring/configuration-files#configuration-based-on-glob-patterns) with our [`disable-type-checked`](../../users/Shared_Configurations.mdx#disable-type-checked) config to disable type checking for just that type of file.
    <Tabs groupId="eslint-config">
      <TabItem value="Flat Config">

      ```js title="eslint.config.js"
      import tseslint from 'typescript-eslint';

      export default tseslint.config(
        // ... the rest of your config ...
        {
          files: ['**/*.js'],
          extends: [tseslint.configs.disableTypeChecked],
        },
      );
      ```

      </TabItem>
      <TabItem value="Legacy Config">

      ```js title=".eslintrc.cjs"
      module.exports = {
        // ... the rest of your config ...
        overrides: [
          {
            extends: ['plugin:@typescript-eslint/disable-type-checked'],
            files: ['./**/*.js'],
          },
        ],
      };
      ```

      </TabItem>
    </Tabs>
    - Alternatively to disable type checking for files manually, you can set `parserOptions: { project: false }` to an override for the files you wish to exclude.
  - If you **do** want to lint the file with [type-aware linting](../../getting-started/Typed_Linting.mdx):
    - Check the `include` option of each of the TSConfigs that you provide to `parserOptions.project` - you must ensure that all files match an `include` glob, or else our tooling will not be able to find it.
      - If the file is a `.cjs`, `.js`, or `.mjs` file, make sure [`allowJs`](https://www.typescriptlang.org/tsconfig#allowJs) is enabled.
    - If your file shouldn't be a part of one of your existing tsconfigs (for example, it is a script/tool local to the repo), then consider creating a new tsconfig (we advise calling it `tsconfig.eslint.json`) in your project root which lists this file in its `include`. For an example of this, you can check out the configuration we use in this repo:
      - [`tsconfig.eslint.json`](https://github.com/typescript-eslint/typescript-eslint/blob/main/tsconfig.eslint.json)
      - [`eslint.config.mjs`](https://github.com/typescript-eslint/typescript-eslint/blob/main/eslint.config.mjs)

<!-- prettier-ignore-end -->

### More Details

This error may appear from the combination of two things:

- The ESLint configuration for the source file specifies at least one TSConfig file in `parserOptions.project`
- None of those TSConfig files includes the source file being linted
  - Note that files with the same name and different extension may not be recognized by TypeScript: see [`parserOptions.project` docs](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser#parseroptionsproject)

When TSConfig files are specified for parsing a source file, `@typescript-eslint/parser` will use the first TSConfig that is able to include that source file (per [aka.ms/tsconfig#include](https://www.typescriptlang.org/tsconfig#include)) to generate type information.
However, if no specified TSConfig includes the source file, the parser won't be able to generate type information.

This error most commonly happens on config files or similar that are not included in their project TSConfig(s).
For example, many projects have files like:

- An `.eslintrc.cjs` / `eslint.config.js` with `parserOptions.project: ["./tsconfig.json"]`
- A `tsconfig.json` with `include: ["src"]`

In that case, viewing the file in an IDE with the ESLint extension will show the error notice that the file couldn't be linted because it isn't included in `tsconfig.json`.

See our docs on [type aware linting](../../getting-started/Typed_Linting.mdx) for more information.

## I get errors telling me "The file must be included in at least one of the projects provided"

You're using an outdated version of `@typescript-eslint/parser`.
Update to the latest version to see a more informative version of this error message, explained [above](#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file 'backlink to I get errors telling me ESLint was configured to run ...').

<HiddenHeading id="allowdefaultprojectforfiles-glob-too-wide" />

## I get errors telling me "Having many files run with the default project is known to cause performance issues and slow down linting."

These errors are caused by using the [`EXPERIMENTAL_useProjectService`](../../packages/Parser.mdx#experimental_useprojectservice) `allowDefaultProjectForFiles` with an excessively wide glob.
`allowDefaultProjectForFiles` causes a new TypeScript "program" to be built for each "out of project" file it includes, which incurs a performance overhead for each file.

To resolve this error, narrow the glob(s) used for `allowDefaultProjectForFiles` to include fewer files.
For example:

```diff title="eslint.config.js"
parserOptions: {
  EXPERIMENTAL_useProjectService: {
    allowDefaultProjectForFiles: [
-      "**/*.js",
+      "./*.js"
    ]
  }
}
```

You may also need to include more files in your `tsconfig.json`.
For example:

```diff title="tsconfig.json"
"include": [
  "src",
+ "*.js"
]
```

If you cannot do this, please [file an issue on typescript-eslint's typescript-estree package](https://github.com/typescript-eslint/typescript-eslint/issues/new?assignees=&labels=enhancement%2Ctriage&projects=&template=07-enhancement-other.yaml&title=Enhancement%3A+%3Ca+short+description+of+my+proposal%3E) telling us your use case and why you need more out-of-project files linted.
Be sure to include a minimal reproduction we can work with to understand your use case!

## typescript-eslint thinks my variable is never nullish / is `any` / etc., but that is clearly not the case to me

Our type-aware rules almost always trust the type information provided by the TypeScript compiler. Therefore, an easy way to check if our rule is behaving correctly is to inspect the type of the variable in question, such as by hovering over it in your IDE.

If the IDE also shows that the type is never nullish / is `any`, you need to fix the type. A very common case is with the [`no-unnecessary-condition`](/rules/no-unnecessary-condition) rule. Take this code for example:

```ts
let condition = false;

const f = () => (condition = true);
f();

if (condition) {
  //^^^^^^^^^ Unnecessary conditional, value is always falsy.
}
```

You can see that the type of `condition` is actually the literal type `false` by hovering over it in your IDE. In this case, typescript-eslint cannot possible know better than TypeScript itself, so you need to fix the report by fixing the type, such as through an assertion (`let condition = false as boolean`).

If the IDE provides different type information from typescript-eslint's report, then make sure that the TypeScript setup used for your IDE, typescript-eslint, and `tsc` are the same: the same TypeScript version, the same type-checking compiler options, and the same files being included in the project. For example, if a type is declared in another file but that file is not included, the type will become `any`, and cause our `no-unsafe-*` rules to report.

## Are TypeScript project references supported?

Yes, but only with [`EXPERIMENTAL_useProjectService`](../../packages/Parser.mdx#experimental_useprojectservice).

See [issue #2094 discussing project references](https://github.com/typescript-eslint/typescript-eslint/issues/2094) for more details.
